Welcome to EOELAB!

EOELAB 互联云架构规范

EOELAB 互联云架构规范

本文档定义 EOELAB 互联云是什么、由哪些实体组成、必须满足哪些约束与规范。

阅读导览

RFC-0001 引言

系统模型

EOELAB 互联云是一个本地域优先的联邦计算系统，其核心观点是：

联邦系统基于以下默认假设构建：

  1. 网络不可信 —— 通信可能被监听
  2. 节点不可信 —— 任何节点可能离线、被攻陷或误操作
  3. 凭证不可信 —— 成员账户、凭证与设备可能泄露
  4. 联邦关系 ≠ 默认信任 —— 建立连接不代表授予特权
  5. 联邦设施不可达 —— 短时离线视为正常
  6. 本地域自负责 —— 自身资源与业务数据的最终责任在本地域

协作原则

我们是一个面向联邦基础设施与自治系统的技术社区。

我们鼓励：

我们不接受：

核心实体

  1. 本地域：基于Incus的自治系统，拥有完整的权限认证能力与独立的调度能力（vm lxc oci同层调度）
  2. 本地服务设备：加入联邦并提供服务，但不具备自治能力的节点
  3. 本地设备：加入联邦只访问且不提供服务的设备

RFC-0002 本地域

本地域是一个有唯一 Incus 控制面，能独立对外提供服务的本地Incus节点/集群。

本地域可以架构为：

  1. 单Incus节点
  2. 集群：一个封闭网络设施下的所有节点组成的集合，满足：
    • 存在三个及以上Incus节点组成集群
    • 低延迟网络互通（L2/L3）
    • 数据设施接口一致

注：双节点只能作为两个独立的单节点管理，不得建立集群。

核心本地域

  1. 核心本地域（coreNumber命名）是由 admin 团队长期维护、持续提供公共服务能力的本地域，这是为了保证 EOELAB 社区与联邦生态具备长期持续运行能力
  2. 核心本地域会额外承担被托管服务，即服务所有者没有设备/没有找到可信维护者托管：
    • 核心本地域将存储业务数据，并提供服务
    • 尽管admin团队承诺绝不泄露数据，但建议业务自行实现端到端加密或主机不可解密的数据保护机制（例如 Nextcloud E2EE）避免意外
  3. 由于资源限制，核心本地域可能根据资源情况限制服务接入
  4. 默认情况下，所有成员都会被认证设施中的core项目分配角色权限

RFC-0003 计算设施

运行时

类型技术定位说明
虚拟化KVM（VM）需要内核特权时的特殊运行时有性能损失与额外负担，启动较慢
系统层容器LXC标准运行时仅支持 Linux，禁止特权容器
应用层容器OCI服务运行时常规 OCI 容器

节点配置

配置项要求
主机名DomainPrefix-Number，DomainPrefix 为联邦内唯一的本地域标识，Number 从 1 开始；例如 core0-1
根文件系统Btrfs，使用 raid1/10 作为数据冗余策略
登录方式仅支持 SSH 密钥登录，禁止使用密码验证
操作系统Debian stable + Incus stable（https://github.com/zabbly/incus）
时间同步Debian stable 默认通过 systemd-timesyncd 维持 UTC 同步，无需额外配置 NTP

大页内存与 swap

嵌套 OCI 容器

特指在 LXC 运行时里嵌套运行 OCI 容器。由于 lxcfs 仅为 LXC 模拟了 procfs 和 sysfs，但嵌套容器会绕过 lxcfs 直接读取宿主机内存容量。由于 Incus 已支持 OCI 调度，默认不允许嵌套；CI/CD 中使用 Kaniko 构建镜像为例外。

实例访问

  1. Terminal：基于 WebUI 实例的 terminal（命令行）/ console（VGA）操作
  2. 上传/下载文件：通过 proxy 设备配置 SSH 端口，在 terminal 添加公钥，启动 SSH 服务，再基于 ssh/scp 传输

鉴权

RFC-0004 数据设施

存储接口

接口是最终暴露在计算设施中的数据入口，由存储服务接口与存储介质评级拼接：

字段含义取值
接口类型数据入口语义bs：块设备；fs：文件系统；os：对象
介质磁盘协议h：SAS/SATA HDD；s：SAS/SATA SSD；n：NVMe SSD
容量容量等级s：≤1T；m：1–4T；l：4–12T；e：>12T
性能性能等级h：更好；m：居中；l：最差（初始设备一般分配 l）
拼接格式<接口类型>_<介质><容量><性能>例：fs_nml = 文件系统 / NVMe / 1–4T / 性能 l

注意：集群必须保证各节点数据接口一致，保证集群可以重平衡实例，但本地存储不支持集群自愈合。

数据温度

类型访问特征典型场景I/O 模式
热数据高频访问，延迟敏感，吞吐量要求高数据库、缓存、实时计算、在线服务随机读写多，写密集
温数据中等频率访问，延迟可容忍数十ms共享文件、CI/CD 产物、容器镜像、日志存储顺序读写多，写较少
冷数据低频访问，延迟不敏感，保留成本优先备份、归档、合规保留、快照极少读，几乎不写

数据保护策略

策略容错能力驱动支持容量适用场景主要缺点
多副本允许 N-1 丢失Btrfs/TrueNAS/Ceph1/N热数据、延迟敏感、故障恢复要求快存储利用率低
RAID-Z允许 Z1/Z2 分别 1/2 盘丢失TrueNASZ1: N-1/N；Z2: N-2/N温/冷数据、大容量、写入频率低写入性能差、重建慢且风险高
纠删码（EC）允许任意 M 块丢失CephK/K+M大规模/大容量、读取多写入有编码开销、小文件放大

数据管理策略

  1. 热数据无论如何都用多副本，性能优先，恢复快，不引入编码开销；最小副本数：Btrfs/TrueNAS 为 2，Ceph 为 3
  2. 温/冷数据根据底座选择编码方式：TrueNAS 用 RAID-Z（Z2 优先，容量受限才用 Z1）；Ceph 用 EC（温数据 4+2，冷数据 8+3 或更高；磁盘极少时用多副本避免小文件放大）
  3. 对于典型 SSD/HDD 混合场景，遵循“显式配置优于缓存”原则，将相同介质与性能等级的磁盘组池而不使用分层缓存
  4. 多节点部署优先采用计算与存储分离架构；仅在可接受停机、临时高负载或数据与计算强绑定场景使用本地存储

存储驱动

底座接口适用规模说明
Btrfsfs本地存储节点本地提供
TrueNASbs单机/小/中规模（3–6 节点）命名 nas；不支持双机
Cephbs/fs/os大/超大规模（≥7 节点）命名 ceph-Number 或与计算设施同名；EC 4+2 起步

Ceph 架设方式：

  1. 与计算设施聚合为超融合设施（当存储高负载、与计算扩容比例失衡、或与计算争用资源时，考虑独立集群）
  2. 独立 Ceph 集群，节点命名为 ceph-Number

Ceph 集群网络：使用独立的 IP 子网隔离，接入网口配置同网段静态 IP 且不设网关；可使用同一台交换机（无需 VLAN）或单独交换机，不依赖路由器。

RFC-0005 网络设施

本地域内会存在固有的两个网络模型：

  1. 物理网络：由真实网络设备（包括 IPMI）组成的物理网络，用于 Incus 集群本地物理互联
  2. 虚拟网络：使用 bridge/OVN 作为实例网络接入/实例间互联的内部网络，是完全受 Incus 控制的虚拟网络设施，支持 ACL、NAT/地址管理、网络隔离、流量观测与策略控制

物理网络架设

带宽数据设施需求业务需求推荐方案
1/2.5G小规模共享存储（1G 仅归档）标准业务，非 HPC/GPU电口（RJ45 + CAT6），无 RDMA，无光纤
10G中规模共享存储标准业务，非 HPC/GPU光口（SFP+ + DAC）+ RoCEv2；不推荐 10G 电口
≥40G大/超大规模共享存储轻量 HPC/GPU光口（QSFP+ + DAC）+ 强制 RoCEv2

注：

公网接入架构

  1. 使用硬件路由器/防火墙作为本地域网关，不使用软定义网络设备
  2. 一个本地域只有一个子域名证书绑定的公网出口
  3. 接入形式：
    • NAT 型：网关接入公网，下发 RFC1918 私网地址到节点；本地域入口解析到网关，通过端口转发/DMZ 主机将流量转发到节点；若网关接入公网 IPv6 但下发私网地址，则关闭物理 IPv6 网络
    • 互通型：网关接入公网，下发公网地址到节点；本地域入口直接解析到节点

虚拟网络架设

  1. 默认仅启用 IPv4 NAT 网络；IPv6 属于可选能力而非默认要求
  2. 单节点使用 bridge，集群使用 ovn, 整个本地域有且仅有一个虚拟网络,命名为INTERFACE-Domain
  3. 地址池默认使用 172.16.0.0/12
  4. 实例网络接入设备默认 eth0；VM 在需要 proxy 设备时可设置静态地址
  5. 实例使用 proxy 设备做端口转发以暴露服务
  6. SR-IOV 仅在明确高性能网络需求（如 GPU RDMA、特定 HPC 场景）时考虑，不作为标准网络设施

ACL 规则

ACL 用于约束虚拟网络行为。

最终策略包含多个ACL规则的组合： * 例如只希望访问互联网：放行所有出入站流量，丢弃私网出入站流量（10.0.0.0/8、172.16.0.0/12、192.168.0.0/16），使实例只能访问互联网而不能互相访问/连接。

RFC-0006 联邦设施

为了克服本地域权限模型重复、无公网设备互联难度大等问题，通过联邦枢纽设施构建联邦计算系统。

联邦设施包括：

联邦设施
├── 枢纽设施
│   ├── 数据库
│   ├── 认证设施
│   ├── 授权设施
│   └── 网络设施
├── 原生设施
│   ├── 联邦域名与证书服务
│   ├── 自托管Runner
│   └── 监控设施
└── 集成设施
    ├── 镜像仓库
    ├── 协作设施
    └── 公告设施

枢纽设施

枢纽设施不采用热备，而是采用可重建备份 + DNS 多端点策略来保证长期可用性。

数据库

仅用于支持联邦设施，不对业务开放。

认证设施

通过统一的认证设施避免重复认证/自托管密钥库。

认证策略

EOELAB 认证策略采用“平台原生凭证优先，外部 IDP 增强为辅”的并行模型：

RBAC 权限模型

Zitadel 提供的权限模型基于 Role 满足类似“准入门槛”的鉴权需求，提供两种级别：

授权设施

Zitadel 仅支持 RBAC 权限模型，额外基于 OpenFGA 提供 ReBAC 权限模型。

网络设施

  1. 联邦网络是节点级 MESH 互联模型，任何节点都可以与另一节点建立 P2P 连接
  2. 互联基于点对点的加密 WireGuard 隧道；标准通信无需额外加密，端到端保护数据应基于 ZITADEL 服务账户的 mTLS 或 OAuth2 access token
  3. 使用 Headscale 标准的 CGNAT 网段：
    • IPv4: 100.64.0.0/10
    • IPv6: fd7a:115c:a1e0::/48
  4. 不得使用反向代理/隧道穿透工具将联邦网络内部端点映射到公网节点上暴露
  5. 提供 .eoelab 作为仅供联邦网络内部使用的域名，节点自动获得 HOSTNAME.eoelab 记录
  6. 节点具备两个公网可达性地址：物理地址（通过本地域网关）和联邦地址（通过 Headscale）

框架

组件endpoint框架说明
控制节点https://hs.eoelab.orgHeadscale禁用内置 DERP 服务器
WebUIhttps://hs.eoelab.org/adminHeadplane
中继节点derper基于客户端自动选择，直接使用 IP 连接

原生设施

联邦域名与证书服务

域名：fdcs.eoelab | Federation DNS & Cert Service

出于更新 TLS 证书/DNS 的需求，统一建立该设施，避免各自独立部署服务。

解析更新

证书更新

自托管 Runner

通用 runner

tag 策略：[size, arch, runtime]

size内存
tiny2–4G
small4–8G
medium8–16G
archruntime
amd64lxc：标准运行时，非特权，部分操作受限
riscv64vm：全功能 runner，拥有特权内核

节点预装 git。优先考虑非特权方案：OCI 容器打包使用 kaniko，OCI 镜像操作使用 crane，拒绝 dind 和 docker 操作 registry。

专用 runner

tag 策略：[purpose]，用于特定用途而非通用构建。例如 mirror：位于海外，负责镜像中国大陆无法访问的 OCI 镜像/软件包。

当前活跃

规格数量
tiny amd64 vm2
medium amd64 lxc1
mirror1

监控设施

用途框架
数据源VictoriaMetrics
可视化Grafana
日志VictoriaLogs
告警Alertmanager

集成设施

镜像仓库

VM/LXC 仓库

使用官方仓库（images.linuxcontainers.org）。不在该仓库内的 OS 视同放弃。

OCI 仓库

使用阿里云容器镜像仓库（crpi-0fzeutaz68uv7lwt.cn-hangzhou.personal.cr.aliyuncs.com/NAMESPACE/REPO）：

OCI 仓库不公开密钥，所有操作通过 Codeberg 仓库的 Actions 完成。

协作设施

EOELAB 使用 QQ 即时通信群组用于联邦协作：协调运维、通知故障/安全事件、日常交流。暂不考虑自建 Matrix。

公告设施

域名：eoelab.codeberg.page

由 Codeberg CI 基于 Zine 框架自动构建并发布，用于发布社区公共通知、联邦规范与文档、服务端点/状态变更、基础设施/维护/安全事件公告。

公共联系方式

我们暂不考虑自建邮件服务器或强行聚合为 NAME@eoelab.org。

Post list